home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / perl5 / 5.8.7 / pod / perlwin32.pod < prev    next >
Text File  |  2006-04-25  |  37KB  |  921 lines
  1. If you read this file _as_is_, just ignore the funny characters you
  2. see. It is written in the POD format (see pod/perlpod.pod) which is
  3. specially designed to be readable as is.
  4.  
  5. =head1 NAME
  6.  
  7. perlwin32 - Perl under Windows
  8.  
  9. =head1 SYNOPSIS
  10.  
  11. These are instructions for building Perl under Windows 9x/NT/2000/XP
  12. on the Intel x86 and Itanium architectures.
  13.  
  14. =head1 DESCRIPTION
  15.  
  16. Before you start, you should glance through the README file
  17. found in the top-level directory to which the Perl distribution
  18. was extracted.  Make sure you read and understand the terms under
  19. which this software is being distributed.
  20.  
  21. Also make sure you read L<BUGS AND CAVEATS> below for the
  22. known limitations of this port.
  23.  
  24. The INSTALL file in the perl top-level has much information that is
  25. only relevant to people building Perl on Unix-like systems.  In
  26. particular, you can safely ignore any information that talks about
  27. "Configure".
  28.  
  29. You may also want to look at two other options for building
  30. a perl that will work on Windows NT:  the README.cygwin and
  31. README.os2 files, each of which give a different set of rules to
  32. build a Perl that will work on Win32 platforms.  Those two methods
  33. will probably enable you to build a more Unix-compatible perl, but
  34. you will also need to download and use various other build-time and
  35. run-time support software described in those files.
  36.  
  37. This set of instructions is meant to describe a so-called "native"
  38. port of Perl to Win32 platforms.  This includes both 32-bit and
  39. 64-bit Windows operating systems.  The resulting Perl requires no
  40. additional software to run (other than what came with your operating
  41. system).  Currently, this port is capable of using one of the
  42. following compilers on the Intel x86 architecture:
  43.  
  44.       Borland C++           version 5.02 or later
  45.       Microsoft Visual C++  version 4.2 or later
  46.       MinGW with gcc        gcc version 2.95.2 or later
  47.  
  48. The last of these is a high quality freeware compiler.  Use version
  49. 3.2.x or later for the best results with this compiler.
  50.  
  51. The Microsoft Visual C++ compiler is also now being given away free in
  52. the "Visual C++ Toolkit 2003", and also as part of the ".NET Framework
  53. SDK".  This is the same compiler that ships with "Visual Studio .NET 2003
  54. Professional".
  55.  
  56. This port can also be built on the Intel IA64 using:
  57.  
  58.       Microsoft Platform SDK    Nov 2001 (64-bit compiler and tools)
  59.  
  60. The MS Platform SDK can be downloaded from http://www.microsoft.com/.
  61.  
  62. This port fully supports MakeMaker (the set of modules that
  63. is used to build extensions to perl).  Therefore, you should be
  64. able to build and install most extensions found in the CPAN sites.
  65. See L<Usage Hints for Perl on Win32> below for general hints about this.
  66.  
  67. =head2 Setting Up Perl on Win32
  68.  
  69. =over 4
  70.  
  71. =item Make
  72.  
  73. You need a "make" program to build the sources.  If you are using
  74. Visual C++ or the Platform SDK tools under Windows NT/2000/XP, nmake
  75. will work.  All other builds need dmake.
  76.  
  77. dmake is a freely available make that has very nice macro features
  78. and parallelability.
  79.  
  80. A port of dmake for Windows is available from:
  81.  
  82.     http://search.cpan.org/dist/dmake/
  83.  
  84. Fetch and install dmake somewhere on your path.
  85.  
  86. There exists a minor coexistence problem with dmake and Borland C++
  87. compilers.  Namely, if a distribution has C files named with mixed
  88. case letters, they will be compiled into appropriate .obj-files named
  89. with all lowercase letters, and every time dmake is invoked
  90. to bring files up to date, it will try to recompile such files again.
  91. For example, Tk distribution has a lot of such files, resulting in
  92. needless recompiles every time dmake is invoked.  To avoid this, you
  93. may use the script "sync_ext.pl" after a successful build.  It is
  94. available in the win32 subdirectory of the Perl source distribution.
  95.  
  96. =item Command Shell
  97.  
  98. Use the default "cmd" shell that comes with NT.  Some versions of the
  99. popular 4DOS/NT shell have incompatibilities that may cause you trouble.
  100. If the build fails under that shell, try building again with the cmd
  101. shell.
  102.  
  103. The nmake Makefile also has known incompatibilities with the
  104. "command.com" shell that comes with Windows 9x.  You will need to
  105. use dmake and makefile.mk to build under Windows 9x.
  106.  
  107. The surest way to build it is on Windows NT/2000/XP, using the cmd shell.
  108.  
  109. Make sure the path to the build directory does not contain spaces.  The
  110. build usually works in this circumstance, but some tests will fail.
  111.  
  112. =item Borland C++
  113.  
  114. If you are using the Borland compiler, you will need dmake.
  115. (The make that Borland supplies is seriously crippled and will not
  116. work for MakeMaker builds.)
  117.  
  118. See L</"Make"> above.
  119.  
  120. =item Microsoft Visual C++
  121.  
  122. The nmake that comes with Visual C++ will suffice for building.
  123. You will need to run the VCVARS32.BAT file, usually found somewhere
  124. like C:\MSDEV4.2\BIN or C:\Program Files\Microsoft Visual Studio\VC98\Bin.
  125. This will set your build environment.
  126.  
  127. You can also use dmake to build using Visual C++; provided, however,
  128. you set OSRELEASE to "microsft" (or whatever the directory name
  129. under which the Visual C dmake configuration lives) in your environment
  130. and edit win32/config.vc to change "make=nmake" into "make=dmake".  The
  131. latter step is only essential if you want to use dmake as your default
  132. make for building extensions using MakeMaker.
  133.  
  134. =item Microsoft Visual C++ Toolkit 2003
  135.  
  136. This free toolkit contains the same compiler and linker that ship with
  137. Visual Studio .NET 2003 Professional, but doesn't contain everything
  138. necessary to build Perl.
  139.  
  140. You will also need to download the "Platform SDK" (the "Core SDK" and "MDAC
  141. SDK" components are required) for header files, libraries and rc.exe, and
  142. ".NET Framework SDK" for more libraries and nmake.exe.  Note that the latter
  143. (which also includes the free compiler and linker) requires the ".NET
  144. Framework Redistributable" to be installed first.  This can be downloaded and
  145. installed separately, but is included in the "Visual C++ Toolkit 2003" anyway.
  146.  
  147. These packages can all be downloaded by searching in the Download Center at
  148. http://www.microsoft.com/downloads/search.aspx?displaylang=en
  149.  
  150. The Platform SDK packages can also be obtained from the Platform SDK Update
  151. site: http://www.microsoft.com/msdownload/platformsdk/sdkupdate  Note that this
  152. site requires Internet Explorer 5.0 or later to function, but the site's home
  153. page currently gives links to two download pages for users of other browsers:
  154.  
  155. For Windows XP Service Pack 2:
  156. http://www.microsoft.com/msdownload/platformsdk/sdkupdate/XPSP2FULLInstall.htm
  157.  
  158. For Windows Server 2003:
  159. http://www.microsoft.com/msdownload/platformsdk/sdkupdate/psdk-full.htm
  160.  
  161. According to the download pages the Toolkit and the .NET Framework SDK are only
  162. supported on Windows 2000/XP/2003, so trying to use these tools on Windows
  163. 95/98/ME and even Windows NT probably won't work.
  164.  
  165. Install the Toolkit first, then the Platform SDK, then the .NET Framework SDK.
  166. Setup your environment as follows (assuming default installation locations
  167. were chosen):
  168.  
  169.     SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin;C:\Program Files\Microsoft SDK\Bin;C:\Program Files\Microsoft.NET\SDK\v1.1\Bin
  170.     SET INCLUDE=C:\Program Files\Microsoft Visual C++ Toolkit 2003\include;C:\Program Files\Microsoft SDK\include;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\include
  171.     SET LIB=C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib;C:\Program Files\Microsoft SDK\lib;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\lib
  172.  
  173. Several required files will still be missing:
  174.  
  175. =over 4
  176.  
  177. =item *
  178.  
  179. cvtres.exe is required by link.exe when using a .res file.  It is actually
  180. installed by the .NET Framework SDK, but into a location such as the
  181. following:
  182.  
  183.     C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322
  184.  
  185. Copy it from there to C:\Program Files\Microsoft SDK\Bin
  186.  
  187. =item *
  188.  
  189. lib.exe is normally used to build libraries, but link.exe with the /lib
  190. option also works, so change win32/config.vc to use it instead:
  191.  
  192. Change the line reading:
  193.  
  194.     ar='lib'
  195.  
  196. to:
  197.  
  198.     ar='link /lib'
  199.  
  200. It may also be useful to create a batch file called lib.bat in
  201. C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin containing:
  202.  
  203.     @echo off
  204.     link /lib %*
  205.  
  206. for the benefit of any naughty C extension modules that you might want to build
  207. later which explicitly reference "lib" rather than taking their value from
  208. $Config{ar}.
  209.  
  210. =item *
  211.  
  212. setargv.obj is required to build perlglob.exe (and perl.exe if the USE_SETARGV
  213. option is enabled).  The Platform SDK supplies this object file in source form
  214. in C:\Program Files\Microsoft SDK\src\crt.  Copy setargv.c, cruntime.h and
  215. internal.h from there to some temporary location and build setargv.obj using
  216.  
  217.     cl.exe /c /I. /D_CRTBLD setargv.c
  218.  
  219. Then copy setargv.obj to C:\Program Files\Microsoft SDK\lib
  220.  
  221. Alternatively, if you don't need perlglob.exe and don't need to enable the
  222. USE_SETARGV option then you can safely just remove all mention of $(GLOBEXE)
  223. from win32/Makefile and setargv.obj won't be required anyway.
  224.  
  225. =back
  226.  
  227. Perl should now build using the win32/Makefile.  You will need to edit that
  228. file to comment-out CCTYPE = MSVC60 (since that enables delay-loading of the
  229. Winsock DLL which the free toolkit does not support) and to set CCHOME,
  230. CCINCDIR and CCLIBDIR as per the environment setup above.  You may also want to
  231. change both mentions of the compiler's "-Gf" switch to "-GF" since the former
  232. is deprecated in VC7 and will be removed from future versions.
  233.  
  234. =item Microsoft Platform SDK 64-bit Compiler
  235.  
  236. The nmake that comes with the Platform SDK will suffice for building
  237. Perl.  Make sure you are building within one of the "Build Environment"
  238. shells available after you install the Platform SDK from the Start Menu.
  239.  
  240. =item MinGW release 3 with gcc
  241.  
  242. The latest release of MinGW at the time of writing is 3.1.0, which contains 
  243. gcc-3.2.3.  It can be downloaded here:
  244.  
  245.     http://www.mingw.org/
  246.  
  247. Perl also compiles with earlier releases of gcc (2.95.2 and up).  See below
  248. for notes about using earlier versions of MinGW/gcc.
  249.  
  250. You also need dmake.  See L</"Make"> above on how to get it.
  251.  
  252. =item MinGW release 1 with gcc
  253.  
  254. The MinGW-1.1 bundle contains gcc-2.95.3.
  255.  
  256. Make sure you install the binaries that work with MSVCRT.DLL as indicated
  257. in the README for the GCC bundle.  You may need to set up a few environment
  258. variables (usually ran from a batch file).
  259.  
  260. There are a couple of problems with the version of gcc-2.95.2-msvcrt.exe
  261. released 7 November 1999:
  262.  
  263. =over
  264.  
  265. =item *
  266.  
  267. It left out a fix for certain command line quotes.  To fix this, be sure
  268. to download and install the file fixes/quote-fix-msvcrt.exe from the above
  269. ftp location.
  270.  
  271. =item *
  272.  
  273. The definition of the fpos_t type in stdio.h may be wrong.  If your
  274. stdio.h has this problem, you will see an exception when running the
  275. test t/lib/io_xs.t.  To fix this, change the typedef for fpos_t from
  276. "long" to "long long" in the file i386-mingw32msvc/include/stdio.h,
  277. and rebuild.
  278.  
  279. =back
  280.  
  281. A potentially simpler to install (but probably soon-to-be-outdated) bundle
  282. of the above package with the mentioned fixes already applied is available
  283. here:
  284.  
  285.     http://downloads.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip
  286.     ftp://ftp.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip
  287.  
  288. =back
  289.  
  290. =head2 Building
  291.  
  292. =over 4
  293.  
  294. =item *
  295.  
  296. Make sure you are in the "win32" subdirectory under the perl toplevel.
  297. This directory contains a "Makefile" that will work with
  298. versions of nmake that come with Visual C++ or the Platform SDK, and
  299. a dmake "makefile.mk" that will work for all supported compilers.  The
  300. defaults in the dmake makefile are setup to build using MinGW/gcc.
  301.  
  302. =item *
  303.  
  304. Edit the makefile.mk (or Makefile, if you're using nmake) and change 
  305. the values of INST_DRV and INST_TOP.   You can also enable various
  306. build flags.  These are explained in the makefiles.
  307.  
  308. Note that it is generally not a good idea to try to build a perl with
  309. INST_DRV and INST_TOP set to a path that already exists from a previous
  310. build.  In particular, this may cause problems with the
  311. lib/ExtUtils/t/Embed.t test, which attempts to build a test program and
  312. may end up building against the installed perl's lib/CORE directory rather
  313. than the one being tested.
  314.  
  315. You will have to make sure that CCTYPE is set correctly and that 
  316. CCHOME points to wherever you installed your compiler.
  317.  
  318. The default value for CCHOME in the makefiles for Visual C++
  319. may not be correct for some versions.  Make sure the default exists
  320. and is valid.
  321.  
  322. If you have either the source or a library that contains des_fcrypt(),
  323. enable the appropriate option in the makefile.  A ready-to-use version
  324. of fcrypt.c, based on the version originally written by Eric Young at
  325. ftp://ftp.funet.fi/pub/crypt/mirrors/dsi/libdes/, is bundled with the
  326. distribution and CRYPT_SRC is set to use it.
  327. Alternatively, if you have built a library that contains des_fcrypt(),
  328. you can set CRYPT_LIB to point to the library name.
  329. Perl will also build without des_fcrypt(), but the crypt() builtin will
  330. fail at run time.
  331.  
  332. Be sure to read the instructions near the top of the makefiles carefully.
  333.  
  334. =item *
  335.  
  336. Type "dmake" (or "nmake" if you are using that make).
  337.  
  338. This should build everything.  Specifically, it will create perl.exe,
  339. perl58.dll at the perl toplevel, and various other extension dll's
  340. under the lib\auto directory.  If the build fails for any reason, make
  341. sure you have done the previous steps correctly.
  342.  
  343. =back
  344.  
  345. =head2 Testing Perl on Win32
  346.  
  347. Type "dmake test" (or "nmake test").  This will run most of the tests from
  348. the testsuite (many tests will be skipped).
  349.  
  350. There should be no test failures when running under Windows NT/2000/XP.
  351. Many tests I<will> fail under Windows 9x due to the inferior command shell.
  352.  
  353. Some test failures may occur if you use a command shell other than the
  354. native "cmd.exe", or if you are building from a path that contains
  355. spaces.  So don't do that.
  356.  
  357. If you are running the tests from a emacs shell window, you may see
  358. failures in op/stat.t.  Run "dmake test-notty" in that case.
  359.  
  360. If you're using the Borland compiler, you may see a failure in op/taint.t
  361. arising from the inability to find the Borland Runtime DLLs on the system
  362. default path.  You will need to copy the DLLs reported by the messages
  363. from where Borland chose to install it, into the Windows system directory
  364. (usually somewhere like C:\WINNT\SYSTEM32) and rerun the test.
  365.  
  366. If you're using Borland compiler versions 5.2 and below, you may run into
  367. problems finding the correct header files when building extensions.  For
  368. example, building the "Tk" extension may fail because both perl and Tk
  369. contain a header file called "patchlevel.h".  The latest Borland compiler
  370. (v5.5) is free of this misbehaviour, and it even supports an
  371. option -VI- for backward (bugward) compatibility for using the old Borland
  372. search algorithm  to locate header files.
  373.  
  374. If you run the tests on a FAT partition, you may see some failures for
  375. C<link()> related tests:
  376.  
  377.     Failed Test                     Stat Wstat Total Fail  Failed  List
  378.  
  379.     ../ext/IO/lib/IO/t/io_dup.t                    6    4  66.67%  2-5
  380.     ../lib/File/Temp/t/mktemp.t                    9    1  11.11%  2
  381.     ../lib/File/Temp/t/posix.t                     7    1  14.29%  3
  382.     ../lib/File/Temp/t/security.t                 13    1   7.69%  2
  383.     ../lib/File/Temp/t/tempfile.t                 20    2  10.00%  2 4
  384.     comp/multiline.t                               6    2  33.33%  5-6
  385.     io/dup.t                                       8    6  75.00%  2-7
  386.     op/write.t                                    47    7  14.89%  1-3 6 9-11
  387.  
  388. Testing on NTFS avoids these errors.
  389.  
  390. Furthermore, you should make sure that during C<make test> you do not
  391. have any GNU tool packages in your path: some toolkits like Unixutils
  392. include some tools (C<type> for instance) which override the Windows
  393. ones and makes tests fail. Remove them from your path while testing to
  394. avoid these errors.
  395.  
  396. Please report any other failures as described under L<BUGS AND CAVEATS>.
  397.  
  398. =head2 Installation of Perl on Win32
  399.  
  400. Type "dmake install" (or "nmake install").  This will put the newly
  401. built perl and the libraries under whatever C<INST_TOP> points to in the
  402. Makefile.  It will also install the pod documentation under
  403. C<$INST_TOP\$INST_VER\lib\pod> and HTML versions of the same under
  404. C<$INST_TOP\$INST_VER\lib\pod\html>.
  405.  
  406. To use the Perl you just installed you will need to add a new entry to
  407. your PATH environment variable: C<$INST_TOP\bin>, e.g.
  408.  
  409.     set PATH=c:\perl\bin;%PATH%
  410.  
  411. If you opted to uncomment C<INST_VER> and C<INST_ARCH> in the makefile
  412. then the installation structure is a little more complicated and you will
  413. need to add two new PATH components instead: C<$INST_TOP\$INST_VER\bin> and
  414. C<$INST_TOP\$INST_VER\bin\$ARCHNAME>, e.g.
  415.  
  416.     set PATH=c:\perl\5.6.0\bin;c:\perl\5.6.0\bin\MSWin32-x86;%PATH%
  417.  
  418. =head2 Usage Hints for Perl on Win32
  419.  
  420. =over 4
  421.  
  422. =item Environment Variables
  423.  
  424. The installation paths that you set during the build get compiled
  425. into perl, so you don't have to do anything additional to start
  426. using that perl (except add its location to your PATH variable).
  427.  
  428. If you put extensions in unusual places, you can set PERL5LIB
  429. to a list of paths separated by semicolons where you want perl
  430. to look for libraries.  Look for descriptions of other environment
  431. variables you can set in L<perlrun>.
  432.  
  433. You can also control the shell that perl uses to run system() and
  434. backtick commands via PERL5SHELL.  See L<perlrun>.
  435.  
  436. Perl does not depend on the registry, but it can look up certain default
  437. values if you choose to put them there.  Perl attempts to read entries from
  438. C<HKEY_CURRENT_USER\Software\Perl> and C<HKEY_LOCAL_MACHINE\Software\Perl>.
  439. Entries in the former override entries in the latter.  One or more of the
  440. following entries (of type REG_SZ or REG_EXPAND_SZ) may be set:
  441.  
  442.     lib-$]        version-specific standard library path to add to @INC
  443.     lib            standard library path to add to @INC
  444.     sitelib-$]        version-specific site library path to add to @INC
  445.     sitelib        site library path to add to @INC
  446.     vendorlib-$]    version-specific vendor library path to add to @INC
  447.     vendorlib        vendor library path to add to @INC
  448.     PERL*        fallback for all %ENV lookups that begin with "PERL"
  449.  
  450. Note the C<$]> in the above is not literal.  Substitute whatever version
  451. of perl you want to honor that entry, e.g. C<5.6.0>.  Paths must be
  452. separated with semicolons, as usual on win32.
  453.  
  454. =item File Globbing
  455.  
  456. By default, perl handles file globbing using the File::Glob extension,
  457. which provides portable globbing.
  458.  
  459. If you want perl to use globbing that emulates the quirks of DOS
  460. filename conventions, you might want to consider using File::DosGlob
  461. to override the internal glob() implementation.  See L<File::DosGlob> for
  462. details.
  463.  
  464. =item Using perl from the command line
  465.  
  466. If you are accustomed to using perl from various command-line
  467. shells found in UNIX environments, you will be less than pleased
  468. with what Windows offers by way of a command shell.
  469.  
  470. The crucial thing to understand about the Windows environment is that
  471. the command line you type in is processed twice before Perl sees it.
  472. First, your command shell (usually CMD.EXE on Windows NT, and
  473. COMMAND.COM on Windows 9x) preprocesses the command line, to handle
  474. redirection, environment variable expansion, and location of the
  475. executable to run. Then, the perl executable splits the remaining
  476. command line into individual arguments, using the C runtime library
  477. upon which Perl was built.
  478.  
  479. It is particularly important to note that neither the shell nor the C
  480. runtime do any wildcard expansions of command-line arguments (so
  481. wildcards need not be quoted).  Also, the quoting behaviours of the
  482. shell and the C runtime are rudimentary at best (and may, if you are
  483. using a non-standard shell, be inconsistent).  The only (useful) quote
  484. character is the double quote (").  It can be used to protect spaces
  485. and other special characters in arguments.
  486.  
  487. The Windows NT documentation has almost no description of how the
  488. quoting rules are implemented, but here are some general observations
  489. based on experiments: The C runtime breaks arguments at spaces and
  490. passes them to programs in argc/argv.  Double quotes can be used to
  491. prevent arguments with spaces in them from being split up.  You can
  492. put a double quote in an argument by escaping it with a backslash and
  493. enclosing the whole argument within double quotes.  The backslash and
  494. the pair of double quotes surrounding the argument will be stripped by
  495. the C runtime.
  496.  
  497. The file redirection characters "E<lt>", "E<gt>", and "|" can be quoted by
  498. double quotes (although there are suggestions that this may not always
  499. be true).  Single quotes are not treated as quotes by the shell or
  500. the C runtime, they don't get stripped by the shell (just to make
  501. this type of quoting completely useless).  The caret "^" has also
  502. been observed to behave as a quoting character, but this appears
  503. to be a shell feature, and the caret is not stripped from the command
  504. line, so Perl still sees it (and the C runtime phase does not treat
  505. the caret as a quote character).
  506.  
  507. Here are some examples of usage of the "cmd" shell:
  508.  
  509. This prints two doublequotes:
  510.  
  511.     perl -e "print '\"\"' "
  512.  
  513. This does the same:
  514.  
  515.     perl -e "print \"\\\"\\\"\" "
  516.  
  517. This prints "bar" and writes "foo" to the file "blurch":
  518.  
  519.     perl -e "print 'foo'; print STDERR 'bar'" > blurch
  520.  
  521. This prints "foo" ("bar" disappears into nowhereland):
  522.  
  523.     perl -e "print 'foo'; print STDERR 'bar'" 2> nul
  524.  
  525. This prints "bar" and writes "foo" into the file "blurch":
  526.  
  527.     perl -e "print 'foo'; print STDERR 'bar'" 1> blurch
  528.  
  529. This pipes "foo" to the "less" pager and prints "bar" on the console:
  530.  
  531.     perl -e "print 'foo'; print STDERR 'bar'" | less
  532.  
  533. This pipes "foo\nbar\n" to the less pager:
  534.  
  535.     perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less
  536.  
  537. This pipes "foo" to the pager and writes "bar" in the file "blurch":
  538.  
  539.     perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
  540.  
  541.  
  542. Discovering the usefulness of the "command.com" shell on Windows 9x
  543. is left as an exercise to the reader :)
  544.  
  545. One particularly pernicious problem with the 4NT command shell for
  546. Windows NT is that it (nearly) always treats a % character as indicating
  547. that environment variable expansion is needed.  Under this shell, it is
  548. therefore important to always double any % characters which you want
  549. Perl to see (for example, for hash variables), even when they are
  550. quoted.
  551.  
  552. =item Building Extensions
  553.  
  554. The Comprehensive Perl Archive Network (CPAN) offers a wealth
  555. of extensions, some of which require a C compiler to build.
  556. Look in http://www.cpan.org/ for more information on CPAN.
  557.  
  558. Note that not all of the extensions available from CPAN may work
  559. in the Win32 environment; you should check the information at
  560. http://testers.cpan.org/ before investing too much effort into
  561. porting modules that don't readily build.
  562.  
  563. Most extensions (whether they require a C compiler or not) can
  564. be built, tested and installed with the standard mantra:
  565.  
  566.     perl Makefile.PL
  567.     $MAKE
  568.     $MAKE test
  569.     $MAKE install
  570.  
  571. where $MAKE is whatever 'make' program you have configured perl to
  572. use.  Use "perl -V:make" to find out what this is.  Some extensions
  573. may not provide a testsuite (so "$MAKE test" may not do anything or
  574. fail), but most serious ones do.
  575.  
  576. It is important that you use a supported 'make' program, and
  577. ensure Config.pm knows about it.  If you don't have nmake, you can
  578. either get dmake from the location mentioned earlier or get an
  579. old version of nmake reportedly available from:
  580.  
  581.  http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe
  582.  
  583. Another option is to use the make written in Perl, available from
  584. CPAN.
  585.  
  586.     http://www.cpan.org/modules/by-module/Make/
  587.  
  588. You may also use dmake.  See L</"Make"> above on how to get it.
  589.  
  590. Note that MakeMaker actually emits makefiles with different syntax
  591. depending on what 'make' it thinks you are using.  Therefore, it is
  592. important that one of the following values appears in Config.pm:
  593.  
  594.     make='nmake'    # MakeMaker emits nmake syntax
  595.     make='dmake'    # MakeMaker emits dmake syntax
  596.     any other value    # MakeMaker emits generic make syntax
  597.                     (e.g GNU make, or Perl make)
  598.  
  599. If the value doesn't match the 'make' program you want to use,
  600. edit Config.pm to fix it.
  601.  
  602. If a module implements XSUBs, you will need one of the supported
  603. C compilers.  You must make sure you have set up the environment for
  604. the compiler for command-line compilation.
  605.  
  606. If a module does not build for some reason, look carefully for
  607. why it failed, and report problems to the module author.  If
  608. it looks like the extension building support is at fault, report
  609. that with full details of how the build failed using the perlbug
  610. utility.
  611.  
  612. =item Command-line Wildcard Expansion
  613.  
  614. The default command shells on DOS descendant operating systems (such
  615. as they are) usually do not expand wildcard arguments supplied to
  616. programs.  They consider it the application's job to handle that.
  617. This is commonly achieved by linking the application (in our case,
  618. perl) with startup code that the C runtime libraries usually provide.
  619. However, doing that results in incompatible perl versions (since the
  620. behavior of the argv expansion code differs depending on the
  621. compiler, and it is even buggy on some compilers).  Besides, it may
  622. be a source of frustration if you use such a perl binary with an
  623. alternate shell that *does* expand wildcards.
  624.  
  625. Instead, the following solution works rather well. The nice things
  626. about it are 1) you can start using it right away; 2) it is more 
  627. powerful, because it will do the right thing with a pattern like
  628. */*/*.c; 3) you can decide whether you do/don't want to use it; and
  629. 4) you can extend the method to add any customizations (or even 
  630. entirely different kinds of wildcard expansion).
  631.  
  632.     C:\> copy con c:\perl\lib\Wild.pm
  633.     # Wild.pm - emulate shell @ARGV expansion on shells that don't
  634.     use File::DosGlob;
  635.     @ARGV = map {
  636.               my @g = File::DosGlob::glob($_) if /[*?]/;
  637.               @g ? @g : $_;
  638.             } @ARGV;
  639.     1;
  640.     ^Z
  641.     C:\> set PERL5OPT=-MWild
  642.     C:\> perl -le "for (@ARGV) { print }" */*/perl*.c
  643.     p4view/perl/perl.c
  644.     p4view/perl/perlio.c
  645.     p4view/perl/perly.c
  646.     perl5.005/win32/perlglob.c
  647.     perl5.005/win32/perllib.c
  648.     perl5.005/win32/perlglob.c
  649.     perl5.005/win32/perllib.c
  650.     perl5.005/win32/perlglob.c
  651.     perl5.005/win32/perllib.c
  652.  
  653. Note there are two distinct steps there: 1) You'll have to create
  654. Wild.pm and put it in your perl lib directory. 2) You'll need to
  655. set the PERL5OPT environment variable.  If you want argv expansion
  656. to be the default, just set PERL5OPT in your default startup
  657. environment.
  658.  
  659. If you are using the Visual C compiler, you can get the C runtime's
  660. command line wildcard expansion built into perl binary.  The resulting
  661. binary will always expand unquoted command lines, which may not be
  662. what you want if you use a shell that does that for you.  The expansion
  663. done is also somewhat less powerful than the approach suggested above.
  664.  
  665. =item Win32 Specific Extensions
  666.  
  667. A number of extensions specific to the Win32 platform are available
  668. from CPAN.  You may find that many of these extensions are meant to
  669. be used under the Activeware port of Perl, which used to be the only
  670. native port for the Win32 platform.  Since the Activeware port does not
  671. have adequate support for Perl's extension building tools, these
  672. extensions typically do not support those tools either and, therefore,
  673. cannot be built using the generic steps shown in the previous section.
  674.  
  675. To ensure smooth transitioning of existing code that uses the
  676. ActiveState port, there is a bundle of Win32 extensions that contains
  677. all of the ActiveState extensions and several other Win32 extensions from
  678. CPAN in source form, along with many added bugfixes, and with MakeMaker
  679. support.  This bundle is available at:
  680.  
  681.    http://www.cpan.org/modules/by-module/Win32/libwin32-0.191.zip
  682.  
  683. See the README in that distribution for building and installation
  684. instructions.  Look for later versions that may be available at the
  685. same location.
  686.  
  687. =item Notes on 64-bit Windows
  688.  
  689. Windows .NET Server supports the LLP64 data model on the Intel Itanium
  690. architecture.
  691.  
  692. The LLP64 data model is different from the LP64 data model that is the
  693. norm on 64-bit Unix platforms.  In the former, C<int> and C<long> are
  694. both 32-bit data types, while pointers are 64 bits wide.  In addition,
  695. there is a separate 64-bit wide integral type, C<__int64>.  In contrast,
  696. the LP64 data model that is pervasive on Unix platforms provides C<int>
  697. as the 32-bit type, while both the C<long> type and pointers are of
  698. 64-bit precision.  Note that both models provide for 64-bits of
  699. addressability.
  700.  
  701. 64-bit Windows running on Itanium is capable of running 32-bit x86
  702. binaries transparently.  This means that you could use a 32-bit build
  703. of Perl on a 64-bit system.  Given this, why would one want to build
  704. a 64-bit build of Perl?  Here are some reasons why you would bother:
  705.  
  706. =over
  707.  
  708. =item *
  709.  
  710. A 64-bit native application will run much more efficiently on
  711. Itanium hardware.
  712.  
  713. =item *
  714.  
  715. There is no 2GB limit on process size.
  716.  
  717. =item *
  718.  
  719. Perl automatically provides large file support when built under
  720. 64-bit Windows.
  721.  
  722. =item *
  723.  
  724. Embedding Perl inside a 64-bit application.
  725.  
  726. =back
  727.  
  728. =back
  729.  
  730. =head2 Running Perl Scripts
  731.  
  732. Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
  733. indicate to the OS that it should execute the file using perl.
  734. Win32 has no comparable means to indicate arbitrary files are
  735. executables.
  736.  
  737. Instead, all available methods to execute plain text files on
  738. Win32 rely on the file "extension".  There are three methods
  739. to use this to execute perl scripts:
  740.  
  741. =over 8
  742.  
  743. =item 1
  744.  
  745. There is a facility called "file extension associations" that will
  746. work in Windows NT 4.0.  This can be manipulated via the two
  747. commands "assoc" and "ftype" that come standard with Windows NT
  748. 4.0.  Type "ftype /?" for a complete example of how to set this
  749. up for perl scripts (Say what?  You thought Windows NT wasn't
  750. perl-ready? :).
  751.  
  752. =item 2
  753.  
  754. Since file associations don't work everywhere, and there are
  755. reportedly bugs with file associations where it does work, the
  756. old method of wrapping the perl script to make it look like a
  757. regular batch file to the OS, may be used.  The install process
  758. makes available the "pl2bat.bat" script which can be used to wrap
  759. perl scripts into batch files.  For example:
  760.  
  761.     pl2bat foo.pl
  762.  
  763. will create the file "FOO.BAT".  Note "pl2bat" strips any
  764. .pl suffix and adds a .bat suffix to the generated file.
  765.  
  766. If you use the 4DOS/NT or similar command shell, note that
  767. "pl2bat" uses the "%*" variable in the generated batch file to
  768. refer to all the command line arguments, so you may need to make
  769. sure that construct works in batch files.  As of this writing,
  770. 4DOS/NT users will need a "ParameterChar = *" statement in their
  771. 4NT.INI file or will need to execute "setdos /p*" in the 4DOS/NT
  772. startup file to enable this to work.
  773.  
  774. =item 3
  775.  
  776. Using "pl2bat" has a few problems:  the file name gets changed,
  777. so scripts that rely on C<$0> to find what they must do may not
  778. run properly; running "pl2bat" replicates the contents of the
  779. original script, and so this process can be maintenance intensive
  780. if the originals get updated often.  A different approach that
  781. avoids both problems is possible.
  782.  
  783. A script called "runperl.bat" is available that can be copied
  784. to any filename (along with the .bat suffix).  For example,
  785. if you call it "foo.bat", it will run the file "foo" when it is
  786. executed.  Since you can run batch files on Win32 platforms simply
  787. by typing the name (without the extension), this effectively
  788. runs the file "foo", when you type either "foo" or "foo.bat".
  789. With this method, "foo.bat" can even be in a different location
  790. than the file "foo", as long as "foo" is available somewhere on
  791. the PATH.  If your scripts are on a filesystem that allows symbolic
  792. links, you can even avoid copying "runperl.bat".
  793.  
  794. Here's a diversion:  copy "runperl.bat" to "runperl", and type
  795. "runperl".  Explain the observed behavior, or lack thereof. :)
  796. Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
  797.  
  798. =back
  799.  
  800. =head2 Miscellaneous Things
  801.  
  802. A full set of HTML documentation is installed, so you should be
  803. able to use it if you have a web browser installed on your
  804. system.
  805.  
  806. C<perldoc> is also a useful tool for browsing information contained
  807. in the documentation, especially in conjunction with a pager
  808. like C<less> (recent versions of which have Win32 support).  You may
  809. have to set the PAGER environment variable to use a specific pager.
  810. "perldoc -f foo" will print information about the perl operator
  811. "foo".
  812.  
  813. One common mistake when using this port with a GUI library like C<Tk>
  814. is assuming that Perl's normal behavior of opening a command-line
  815. window will go away.  This isn't the case.  If you want to start a copy
  816. of C<perl> without opening a command-line window, use the C<wperl>
  817. executable built during the installation process.  Usage is exactly
  818. the same as normal C<perl> on Win32, except that options like C<-h>
  819. don't work (since they need a command-line window to print to).
  820.  
  821. If you find bugs in perl, you can run C<perlbug> to create a
  822. bug report (you may have to send it manually if C<perlbug> cannot
  823. find a mailer on your system).
  824.  
  825. =head1 BUGS AND CAVEATS
  826.  
  827. Norton AntiVirus interferes with the build process, particularly if 
  828. set to "AutoProtect, All Files, when Opened". Unlike large applications 
  829. the perl build process opens and modifies a lot of files. Having the  
  830. the AntiVirus scan each and every one slows build the process significantly.
  831. Worse, with PERLIO=stdio the build process fails with peculiar messages
  832. as the virus checker interacts badly with miniperl.exe writing configure 
  833. files (it seems to either catch file part written and treat it as suspicious,
  834. or virus checker may have it "locked" in a way which inhibits miniperl
  835. updating it). The build does complete with 
  836.  
  837.    set PERLIO=perlio
  838.  
  839. but that may be just luck. Other AntiVirus software may have similar issues.
  840.  
  841. Some of the built-in functions do not act exactly as documented in
  842. L<perlfunc>, and a few are not implemented at all.  To avoid
  843. surprises, particularly if you have had prior exposure to Perl
  844. in other operating environments or if you intend to write code
  845. that will be portable to other environments, see L<perlport>
  846. for a reasonably definitive list of these differences.
  847.  
  848. Not all extensions available from CPAN may build or work properly
  849. in the Win32 environment.  See L</"Building Extensions">.
  850.  
  851. Most C<socket()> related calls are supported, but they may not
  852. behave as on Unix platforms.  See L<perlport> for the full list.
  853. Perl requires Winsock2 to be installed on the system. If you're
  854. running Win95, you can download Winsock upgrade from here:
  855.  
  856. http://www.microsoft.com/windows95/downloads/contents/WUAdminTools/S_WUNetworkingTools/W95Sockets2/Default.asp
  857.  
  858. Later OS versions already include Winsock2 support.
  859.  
  860. Signal handling may not behave as on Unix platforms (where it
  861. doesn't exactly "behave", either :).  For instance, calling C<die()>
  862. or C<exit()> from signal handlers will cause an exception, since most
  863. implementations of C<signal()> on Win32 are severely crippled.
  864. Thus, signals may work only for simple things like setting a flag
  865. variable in the handler.  Using signals under this port should
  866. currently be considered unsupported.
  867.  
  868. Please send detailed descriptions of any problems and solutions that 
  869. you may find to E<lt>F<perlbug@perl.org>E<gt>, along with the output
  870. produced by C<perl -V>.
  871.  
  872. =head1 ACKNOWLEDGEMENTS
  873.  
  874. The use of a camel with the topic of Perl is a trademark
  875. of O'Reilly and Associates, Inc. Used with permission.
  876.  
  877. =head1 AUTHORS
  878.  
  879. =over 4
  880.  
  881. =item Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
  882.  
  883. =item Gurusamy Sarathy E<lt>gsar@activestate.comE<gt>
  884.  
  885. =item Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
  886.  
  887. =item Jan Dubois E<lt>jand@activestate.comE<gt>
  888.  
  889. =item Steve Hay E<lt>steve.hay@uk.radan.comE<gt>
  890.  
  891. =back
  892.  
  893. This document is maintained by Jan Dubois.
  894.  
  895. =head1 SEE ALSO
  896.  
  897. L<perl>
  898.  
  899. =head1 HISTORY
  900.  
  901. This port was originally contributed by Gary Ng around 5.003_24,
  902. and borrowed from the Hip Communications port that was available
  903. at the time.  Various people have made numerous and sundry hacks
  904. since then.
  905.  
  906. Borland support was added in 5.004_01 (Gurusamy Sarathy).
  907.  
  908. GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).
  909.  
  910. Support for PERL_OBJECT was added in 5.005 (ActiveState Tool Corp).
  911.  
  912. Support for fork() emulation was added in 5.6 (ActiveState Tool Corp).
  913.  
  914. Win9x support was added in 5.6 (Benjamin Stuhl).
  915.  
  916. Support for 64-bit Windows added in 5.8 (ActiveState Corp).
  917.  
  918. Last updated: 15 February 2005
  919.  
  920. =cut
  921.